星辰 Workflow Open API 接口文档
本协议用于描述如何调用星辰 Agent 开发平台 Workflow OpenAPI,您需要先在星辰大模型应用平台完成工作流的创建,调试通过并发布后,即可调用此服务。
一、执行工作流
1. 基础信息
1.1 接口说明
请求方式 | POST |
---|---|
请求地址 | http(s)://xingchen-api.xf-yun.com/workflow/v1/chat/completions |
1.2 接口Demo
接口Demo随后提供。
1.3 接口要求
接口类型: 流式http(s)
接口鉴权: Bearer鉴权
1.4 接口权限说明
鉴权不通过或APPID与当前工作流不匹配,会返回相关流控错误。
2. 请求
2.1 请求协议示例
{
"flow_id": "7265177322515169282",
"uid": "123",
"parameters": {
"AGENT_USER_INPUT": "你好"
},
"ext": {
"bot_id": "workflow",
"caller": "workflow"
},
"stream": true,
"chat_id": "xxx",
"history": [
{
"role": "user",
"content_type": "text",
"content": "你好"
},
{
"role": "assistant",
"content_type": "text",
"content": "你好,我是你的工作助手,请问有什么可以帮您?"
}
]
}
2.2 请求参数
2.2.1 Header
参数名称 | 参数值 | 是否必填 | 说明 |
---|---|---|---|
Authorization | Bearer $API_KEY | 是 | 鉴权key 鉴权码组成:Bearer {API_KEY}:{API_SECRET} |
2.2.2 Body
参数名称 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
flow_id | string | 是 | 工作流id |
uid | string | 否 | 用户id |
stream | bool | 是 | 是否启用流式返回 流式:true 非流式:false |
ext | object | 否 | 用于指定一些额外字段,比如一些插件隐藏字段 暂时用不到 |
parameters | object | 是 | 工作流开始节点的输入参数及取值,你可以在指定工作流的编排页面查看参数列表 {"input1": "xxxxx", "input2": "xxxxx"} |
chat_id | string | 否 | 会话id,用于区分不同的工作流会话,长度不超过32位 |
history | array of history_message object | 否 | 历史对话信息[history_message object]集合 例如 [{"role": "user", "content_type": "text", "content": "你好" },{"role": "assistant", "content_type": "text", "content": "你好,我是你的工作助手,请问有什么可以帮您?" }] |
history_message Object
参数名称 | 参数类型 | 是否必须 | 取值范围 | 默认值 | 说明 |
---|---|---|---|---|---|
role | string | 是 | user, assistant |
发送这条消息的实体 user: 代表该消息是用户发送的。 assistant: 代表该消息是工作流回复的。 | |
content_type | string | 否 | text, image |
text | 消息内容的类型,当前只支持两种类型。若不填写,则默认类型为text text:表示普通文本。 image:表示图片类型。 |
content | string | 是 | 消息内容,如果是image类型这里需要填写图片url |
在处理 history_message object 时,首个元素的 role 必须为 user。交互历史应按照 user -> assistant -> user -> assistant 的顺序进行拼接,默认情况下,user 与 assistant 之间的一对交互视为一轮对话。按对话时间从先到后依次填充。如[{第一次},{第二次}...]
[
// 拼接对话历史信息:
{"role": "user", "content_type" : "text", "content": "湖南有哪些美食"}, // 用户第一个问题 role是user,表示是用户的提问
{"role": "assistant", "content_type" : "text", "content": "湖南有xxxxxx"}, // AI的第一个回复 role是assistant,表示是AI的回复
]
3. 响应
3.1 响应协议示例
3.1.1 流式结果示例
流式输出过程帧
{
"code": 0,
"message": "Success",
"id": "cha000c0076@dx191c21ce879b8f3532",
"created": 123412324431,
"workflow_step": {
"seq": 0,
"progress": 0.4
},
"choices": [
{
"delta": {
"role": "assistant",
"content": "你好,",
"reasoning_content": ""
},
"index": 0,
"finish_reason": null
}
]
}
流式输出结束帧
{
"code": 0,
"message": "Success",
"id": "spf0016609f@dx193193f43cba44d782",
"created": 123412324431,
"workflow_step": {
"seq": 6,
"progress": 1
},
"choices": [
{
"delta": {
"role": "assistant",
"content": "",
"reasoning_content": ""
},
"index": 0,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1,
"completion_tokens": 0,
"total_tokens": 9
}
}
3.1.2 非流式结果示例
{
"code": 0,
"message": "Success",
"id": "cha000b0003@dx1905cd86d6bb86d552",
"choices": [
{
"delta": {
"role": "assistant",
"content": "你好,我是由科大讯飞构建的星火认知智能模型。\n如果你有任何问题或者需要帮助的地方,请随时告诉我!我会尽力为你提供解答和支持。请问有什么可以帮到你的吗?",
"reasoning_content": ""
},
"index": 0,
"finish_reason": "stop",
"finish_reason": ""
}
],
"usage": {
"prompt_tokens": 6,
"completion_tokens": 42,
"total_tokens": 48
}
}
3.1.3 中断事件
当工作流中有问答节点时,工作流会被中断
问答节点中断帧(直接回答)
{
"code": 0,
"message": "Success",
"id": "cha000c0076@dx191c21ce879b8f3532",
"created": 123412324431,
"workflow_step": {
"seq": 0,
"progress": 0.4
},
"choices": [
{
"delta": {
"role": "assistant",
"content": "你好,",
"reasoning_content": ""
},
"index": 0,
"finish_reason": null
}
],
"event_data": {
"event_id": "7336690112690499584",
"event_type": "interrupt",
"need_reply": true,
"value": {
"type": "direct",
"content": "你想购买以下哪个套餐?"
}
}
}
问答节点中断帧(选项回答)
{
"code": 0,
"message": "Success",
"id": "cha000c0076@dx191c21ce879b8f3532",
"created": 123412324431,
"workflow_step": {
"seq": 0,
"progress": 0.4
},
"choices": [
{
"delta": {
"role": "assistant",
"content": "你好,",
"reasoning_content": ""
},
"index": 0,
"finish_reason": null
}
],
"event_data": {
"event_id": "7336690112690499584",
"event_type": "interrupt",
"need_reply": false,
"value": {
"type": "option",
"content": "请选择你的套餐",
"option": [
{
"id": "A",
"text": "年度套餐"
},
{
"id": "B",
"text": "月度套餐"
}
]
}
}
}
3.1.4 异常结果
{
"code": 20805,
"message": "flow id : 7265177322515169282 状态为草稿,请发布",
"id": "spf00dc0001@hf193621572a96806782",
"created": 1732517393,
"choices": [
{
"delta": {
"role": "assistant",
"content": "",
"reasoning_content": ""
},
"finish_reason": "stop"
}
],
"workflow_step": {
"seq": 0,
"progress": 1.0
},
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 0
}
}
3.2 响应参数
3.2.1 响应数据参数
参数名称 | 类型 | 是否必须 | 参数说明 |
---|---|---|---|
code | int | 是 | 错误码,0为成功,非0表示报错 |
message | string | 是 | 错误信息描述 |
id | string | 是 | 服务端会话id |
created | int | 是 | 对话创建时间戳, 单位: s |
workflow_step | object | 是 | 工作流步骤 |
workflow_step.seq | int | 是 | 返回的数据序号,取值为 [0,9999999] |
workflow_step.progress | float | 是 | 工作流进度 |
choices | array | 是 | |
choices.delta | object | 是 | |
choices.delta.role | string | 是 | 工作流的角色 |
choices.delta.content | string | 是 | 工作流输出的内容 |
choices.delta.reasoning_content | string | 是 | 工作流的思维链内容 |
choices.index | int | 是 | 工作流的结果序号,在多候选中使用 |
choices.finish_reason | string | 是 | 当工作流到达自然停止点或用户提供的停止序列时,它将将 finish_reason 设置为 “stop” |
usage | object | 否 | token计量,只在工作流结束帧才会给出 |
usage.prompt_tokens | int | 是 | 工作流请求大模型的token |
usage.completion_tokens | int | 是 | 工作流大模型回复 |
usage.total_tokens | int | 是 | 工作流总的token消耗 |
event_data | object | 否 | 事件数据 |
event_data.event_id | str | 是 | 事件id,用于resume接口恢复事件的标志 |
event_data.event_type | str | 是 | 事件类型,中断时为"interrupt" |
event_data.need_reply | bool | 是 | 问答节点是否必须要求回答 |
event_data.value | object | 是 | 中断数据详情 |
event_data.value.type | str | 是 | 问题类型,枚举值 - direct: 直接回答 - option: 选项回答 |
event_data.value.content | str | 是 | 用户提问内容 |
event_data.value.option | array | 否 | 选项回答时的选项内容 |
3.2.2 结果格式补充说明
模型结果除了普通文本类型,为了满足排版需求,会出现以下的标记语言,建议集成方进行适配:
- markdown(表格、列表等)
二、恢复运行工作流
1. 基础信息
1.1 接口说明
请求方式 | POST |
---|---|
请求地址 | http(s)://xingchen-api.xf-yun.com/workflow/v1/resume |
1.2 接口Demo
接口Demo随后提供。
1.3 接口要求
接口类型: 流式http(s)
2. 请求
2.1 请求协议示例
{
"event_id": "123456789012345",
"event_type": "resume",
"content": "我的姓名是:xxxx, 年龄:xxxx"
}
2.2 请求参数
2.2.1 Header
2.2.2 Body
参数名称 | 参数类型 | 是否必须 | 说明 |
---|---|---|---|
event_id | string | 是 | 事件id,中断类事件发生时由chat和resume接口返回,用于标识同一工作流中一次请求产生的多个事件,值保持一致。 |
event_type | string | 否 | 用于处理事件,默认走恢复。 resume: 恢复 ignore: 忽略 abort: 结束 |
content | string | 是 | 回答内容, 如果是选项回答,只需传选项信息A-Z |
3. 响应
3.1 响应协议示例
3.1.1 流式结果示例
流式输出过程帧
{
"code": 0,
"message": "Success",
"id": "cha000c0076@dx191c21ce879b8f3532",
"created": 123412324431,
"workflow_step": {
"seq": 0,
"progress": 0.4
},
"choices": [
{
"delta": {
"role": "assistant",
"content": "你好,",
"reasoning_content": ""
},
"index": 0,
"finish_reason": null
}
]
}
流式输出结束帧
{
"code": 0,
"message": "Success",
"id": "spf0016609f@dx193193f43cba44d782",
"created": 123412324431,
"workflow_step": {
"seq": 6,
"progress": 1
},
"choices": [
{
"delta": {
"role": "assistant",
"content": "",
"reasoning_content": ""
},
"index": 0,
"finish_reason": "stop"
}
],
"usage": {
"prompt_tokens": 1,
"completion_tokens": 0,
"total_tokens": 9
}
}
3.1.2 非流式结果示例
{
"code": 0,
"message": "Success",
"id": "cha000b0003@dx1905cd86d6bb86d552",
"choices": [
{
"delta": {
"role": "assistant",
"content": "你好,我是由科大讯飞构建的星火认知智能模型。\n如果你有任何问题或者需要帮助的地方,请随时告诉我!我会尽力为你提供解答和支持。请问有什么可以帮到你的吗?",
"reasoning_content": ""
},
"index": 0,
"finish_reason": "stop",
"finish_reason": ""
}
],
"usage": {
"prompt_tokens": 6,
"completion_tokens": 42,
"total_tokens": 48
}
}
3.1.3 中断事件
当工作流中有问答节点时,工作流会被中断
问答节点中断帧(直接回答)
{
"code": 0,
"message": "Success",
"id": "cha000c0076@dx191c21ce879b8f3532",
"created": 123412324431,
"workflow_step": {
"seq": 0,
"progress": 0.4
},
"choices": [
{
"delta": {
"role": "assistant",
"content": "你好,",
"reasoning_content": ""
},
"index": 0,
"finish_reason": null
}
],
"event_data": {
"event_id": "7336690112690499584",
"event_type": "interrupt",
"need_reply": true,
"value": {
"type": "direct",
"content": "你想购买以下哪个套餐?"
}
}
}
问答节点中断帧(选项回答)
{
"code": 0,
"message": "Success",
"id": "cha000c0076@dx191c21ce879b8f3532",
"created": 123412324431,
"workflow_step": {
"seq": 0,
"progress": 0.4
},
"choices": [
{
"delta": {
"role": "assistant",
"content": "你好,",
"reasoning_content": ""
},
"index": 0,
"finish_reason": null
}
],
"event_data": {
"event_id": "7336690112690499584",
"event_type": "interrupt",
"need_reply": false,
"value": {
"type": "option",
"content": "请选择你的套餐",
"option": [
{
"id": "A",
"text": "年度套餐"
},
{
"id": "B",
"text": "月度套餐"
}
]
}
}
}
3.1.4 异常结果
{
"code": 20805,
"message": "flow id : 7265177322515169282 状态为草稿,请发布",
"id": "spf00dc0001@hf193621572a96806782",
"created": 1732517393,
"choices": [
{
"delta": {
"role": "assistant",
"content": "",
"reasoning_content": ""
},
"finish_reason": "stop"
}
],
"workflow_step": {
"seq": 0,
"progress": 1.0
},
"usage": {
"prompt_tokens": 0,
"completion_tokens": 0,
"total_tokens": 0
}
}
4.2 响应参数说明
4.2.1 响应数据参数
参数名称 | 类型 | 是否必须 | 参数说明 |
---|---|---|---|
code | int | 是 | 错误码,0为成功,非0表示报错 |
message | string | 是 | 错误信息描述 |
id | string | 是 | 服务端会话id |
created | int | 是 | 对话创建时间戳, 单位: s |
workflow_step | object | 是 | 工作流步骤 |
workflow_step.seq | int | 是 | 返回的数据序号,取值为 [0,9999999] |
workflow_step.progress | float | 是 | 工作流进度 |
choices | array | 是 | |
choices.delta | object | 是 | |
choices.delta.role | string | 是 | 工作流的角色 |
choices.delta.content | string | 是 | 工作流输出的内容 |
choices.delta.reasoning_content | string | 是 | 工作流的思维链内容 |
choices.index | int | 是 | 工作流的结果序号,在多候选中使用 |
choices.finish_reason | string | 是 | 当工作流到达自然停止点或用户提供的停止序列时,它将将 finish_reason 设置为 “stop” |
usage | object | 否 | token计量,只在工作流结束帧才会给出 |
usage.prompt_tokens | int | 是 | 工作流请求大模型的token |
usage.completion_tokens | int | 是 | 工作流大模型回复 |
usage.total_tokens | int | 是 | 工作流总的token消耗 |
event_data | object | 否 | 事件数据 |
event_data.event_id | str | 是 | 事件id,用于resume接口恢复事件的标志 |
event_data.event_type | str | 是 | 事件类型,中断时为"interrupt" |
event_data.need_reply | bool | 是 | 问答节点是否必须要求回答 |
event_data.value | object | 是 | 中断数据详情 |
event_data.value.type | str | 是 | 问题类型,枚举值 - direct: 直接回答 - option: 选项回答 |
event_data.value.content | str | 是 | 用户提问内容 |
event_data.value.option | array | 否 | 选项回答时的选项内容 |
4.2.2 结果格式补充说明
模型结果除了普通文本类型,为了满足排版需求,会出现以下的标记语言,建议集成方进行适配:
- markdown(表格、列表等)
三、文件上传
1. 基础信息
1.1 接口说明
请求方式 | POST |
---|---|
请求地址 | http(s)://xingchen-api.xf-yun.com/workflow/v1/upload_file |
1.2 接口Demo
curl -X POST 'https://xingchen-api.xf-yun.com/workflow/v1/upload_file' \
--header 'Authorization: Bearer {api_key}' \
--form 'file=@localfile;type=image/[png|jpeg|jpg|webp|gif]
1.3 接口要求
接口类型: 流式http(s)
接口鉴权: Bearer鉴权
2. 请求参数
2.1 Header
参数名称 | 类型 | 是否必须 | 参数说明 |
---|---|---|---|
Authorization | string | 是 | 鉴权 key。Bearer $API_KEY |
Content-Type | string | 是 | multipart/form-data |
2.2 Body
参数名称 | 类型 | 是否必须 | 参数说明 |
---|---|---|---|
file | file | 是 | 要上传的文件 |
3. 响应
3.1 响应协议示例
{
"code": 0,
"message": "success",
"sid": "spf001b23c7@dx1939b17d9e3a4f3700",
"data": {
"url": "xxxxxxxxxx"
}
}
3.2 响应参数说明
参数名称 | 类型 | 参数说明 |
---|---|---|
code | integer | 错误码 |
message | string | 错误描述 |
sid | string | 会话id |
data | object | 错误码 |
data.url | string | 文件的访问外链 |
四、错误码列表
1. 工作流错误
错误码 | 描述 |
---|---|
20201 | 未查找到对应Flow ID |
20202 | Flow ID非法 |
20204 | 工作流未发布 |
20207 | 工作流为草稿状态 |
2. 模型错误
错误码 | 描述 |
---|---|
20303 | 模型请求失败 |
20350 | 升级为ws出现错误 |
20351 | 通过ws读取用户的消息出错 |
20352 | 通过ws向用户发送消息出错 |
20353 | 用户的消息格式有错误 |
20354 | 用户数据的schema错误 |
20355 | 用户参数值有错误 |
20356 | 用户并发错误:当前用户已连接,同一用户不能多处同时连接。 |
20357 | 用户流量受限:服务正在处理用户当前的问题,需等待处理完成后再发送新的请求。(必须要等大模型完全回复之后,才能发送下一个问题)") |
20358 | 服务容量不足,联系工作人员 |
20359 | 和引擎建立连接失败 |
20360 | 接收引擎数据的错误 |
20361 | 发送数据给引擎的错误 |
20362 | 引擎内部错误 |
20363 | 输入内容审核不通过,涉嫌违规,请重新调整输入内容 |
20364 | 输出内容涉及敏感信息,审核不通过,后续结果无法展示给用户 |
20365 | appid在黑名单中 |
20366 | appid授权类的错误。比如:未开通此功能,未开通对应版本,token不足,并发超过授权 等等 |
20367 | 清除历史失败 |
20368 | 表示本次会话内容有涉及违规信息的倾向;建议开发者收到此错误码后给用户一个输入涉及违规的提示 |
20369 | 服务忙,请稍后再试 |
20370 | 请求引擎的参数异常 引擎的schema 检查不通过 |
20371 | 引擎网络异常 |
20372 | token数量超过上限。对话历史+问题的字数太多,需要精简输入 |
20373 | 授权错误:该appId没有相关功能的授权 或者 业务量超过限制 |
20374 | 授权错误:日流控超限。超过当日最大访问量的限制 |
20375 | 授权错误:秒级流控超限。秒级并发超过授权路数限制 |
20376 | 授权错误:并发流控超限。并发路数超过授权路数限制 |
20380 | 外部大模型请求失败 |
3. API授权
错误码 | 描述 |
---|---|
20900 | 鉴权失败:授权限制,服务未授权或授权已到期 |
20901 | 计量鉴权失败:服务超限,业务会话总量超限或日流控超限 |
20902 | 鉴权失败:服务超限,QPS秒级流控超限 |
20903 | 并发鉴权失败:服务超限,并发路数超限 |
4. 文生图
错误码 | 描述 |
---|---|
21200 | 图片生成失败 |
21201 | 图片存储失败 |
21203 | 用户的消息格式有错误 |
21204 | 用户数据的schema错误 |
21205 | 用户参数值有错误 |
21206 | 服务容量不足 |
21207 | 输入审核不通过 |
21208 | 模型生产的图片涉及敏感信息,审核不通过 |
21209 | 文生图超时 |
5. 工具错误
错误码 | 描述 |
---|---|
21800 | 工具请求失败 |
21801 | 工具初始化失败 |
21802 | 工具json协议解析失败 |
21803 | 工具协议校验失败 |
21804 | 工具openapi协议解析失败 |
21805 | 工具body类型不支持 |
21806 | 工具 server 不存在 |
21807 | 官方工具请求失败 |
21808 | 工具不存在 |
21809 | 工具Operation不存在 |
21810 | 工具请求失败,连接异常 |
21811 | 三方工具执行失败 |
21812 | 三方工具请求失败 |
6. 节点执行错误
错误码 | 描述 |
---|---|
20500 | 知识库请求异常 |
20501 | 知识库节点执行异常 |
20502 | 知识库参数异常 |
22500 | 开始节点协议有误 |
22600 | 结束节点协议有误 |
22601 | 结束节点执行失败 |
22701 | 消息节点执行失败 |
21900 | 参数提取失败 |
21600 | 代码执行失败 |
21601 | 代码解释器节点构建失败 |
21602 | 代码节点返回结果类型不符合要求 |
21603 | 代码执行超时 |
22801 | 工作流节点执行失败 |
22802 | 工作流节点执行相应结果格式错误 |
22900 | 变量节点执行失败 |
23100 | 分支节点执行失败 |
23200 | 迭代节点执行失败 |
23300 | 大模型节点执行失败 |
23400 | 工具节点执行失败 |
23500 | 文本拼接节点执行失败 |
23700 | Agent节点执行失败 |
23800 | 问答节点执行失败 |
7. 会话
错误码 | 描述 |
---|---|
20804 | OpenAPI输出超时 |
23900 | 该对话已超时或不存在 |